feat(ledger): record what a change was derived from - #261

Review — approve, no changes

The question this answers — what was this derived from — is genuinely not answerable from the existing ledger, and it is the one you ask when a generated file is wrong and you need to know which input to fix.

Building on the existing ledger rather than adding a provenance store is right for the stated reason: two logs of the same events are two things to keep in step and one place for them to disagree.

The four narrowings are what make this trustworthy rather than merely present:

• Only Read counts. Grep/Glob take a search root and return many paths; calling the root an input claims a derivation the turn did not make, and listing every hit drowns the real inputs in whatever the search swept up. Narrow and true beats wide and approximate — and a provenance field people learn to distrust is worse than no field.
• A failed read is not an input. if (!tr.isError) — it gave the turn nothing, and crediting it sends someone to fix a file that was never opened.
• The file being written is excluded via written. Edit reads its target by construction, so without this every edit looks self-derived.
• Absent rather than empty, in the record and in ledger show. A field that is always present stops being read.

Collected at the single post-dispatch site, same as the ledger append, for the same reason: a per-tool hook is a hook a new tool forgets. That is consistent with the rule AGENTS.md already states, and it is why this stays correct when someone adds a mutating tool.

Calling it a derivation record and not a dependency graph, in the docs, is the right disclaimer — they are easy to confuse and only one of them is true here.

Two observations, neither a change request:

• readsThisTurn accumulates for the whole runAgent call, so a Read early in a long run is credited to a write much later. That matches "what this one turn read" as documented; just noting it is turn-scoped and not read-recency-scoped, which is the more conservative of the two readings.
• normalizeContractPath(cwd, raw) ?? raw keeps an absolute path for a file outside the workspace. Correct — falling back to the raw path is more useful than dropping the input — and worth knowing that derivedFrom is therefore not uniformly workspace-relative.